% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/getblocksnearby.R
\name{getblocksnearby}
\alias{getblocksnearby}
\title{Very fast way to distances to all nearby Census blocks}
\usage{
getblocksnearby(
  sitepoints,
  radius = 3,
  maxradius = 31.07,
  radius_donut_lower_edge = 0,
  avoidorphans = FALSE,
  quadtree = NULL,
  quiet = FALSE,
  parallel = FALSE,
  use_unadjusted_distance = TRUE,
  ...
)
}
\arguments{
\item{sitepoints}{data.table with columns lat, lon giving point locations of sites or facilities around which are circular buffers}

\item{radius}{in miles, defining circular buffer around a site point}

\item{maxradius}{miles distance (max distance to check if not even 1 block point is within radius)}

\item{radius_donut_lower_edge}{radius of lower edge of ring if analyzing ring not full circle}

\item{avoidorphans}{logical If TRUE, then where not even 1 BLOCK internal point is within radius of a SITE,
it keeps looking past radius, up to maxradius, to find nearest 1 BLOCK.
What EJScreen does in that case is report NA, right? So,
does EJAM really need to report stats on residents presumed to be within radius,
if no block centroid is within radius?
Best estimate might be to report indicators from nearest block centroid which is
probably almost always the one your site is sitting inside of,
but ideally would adjust total count to be a fraction of blockwt based on
what is area of circular buffer as fraction of area of block it is apparently inside of.
Setting this to TRUE can produce unexpected results, which will not match EJScreen numbers.

Note that if creating a proximity score, by contrast, you instead want to find nearest 1 SITE if none within radius of this BLOCK.}

\item{quadtree}{(a pointer to the large quadtree object)
created using indexblocks() which uses the SearchTree package.
Takes about 2-5 seconds to create this each time it is needed.
It can be automatically created when the package is attached via the .onAttach() function}

\item{quiet}{Optional. set to TRUE to avoid message about using getblock_diagnostics(),
which is relevant only if a user saved the output of this function.}

\item{parallel}{Not implemented}

\item{use_unadjusted_distance}{logical, whether to find points within unadjusted distance}

\item{...}{passed to \code{\link[=getblocksnearbyviaQuadTree]{getblocksnearbyviaQuadTree()}} or other such functions}
}
\value{
data.table like testoutput_getblocksnearby_10pts_1miles, with
columns named "ejam_uniq_id", "blockid", "distance", etc.
}
\description{
Get distance from each site (e.g., facility) to each
Census block centroid within some radius

Given a set of points and a specified radius,
this function quickly finds all the US Census blocks near each point.
For each point, it uses the specified radius distance and finds the distance to
every block within the circle defined by the radius.
Each block is defined by its Census-provided internal point, by latitude and longitude.

Each point can be the location of a regulated facility or other type of site, and
the blocks are a high-resolution source of information about where
residents live.

Finding which blocks have their internal points in a circle provides
a way to quickly estimate what fraction of a block group is
inside the circular buffer more accurately and more quickly than
areal apportionment of block groups would provide.
}
\details{
See \code{\link[=ejamit]{ejamit()}} for examples.

getblocksnearby() is a wrapper redirecting to the right version, like \code{\link[=getblocksnearbyviaQuadTree]{getblocksnearbyviaQuadTree()}}
Census block "internal points" (defined by Census Bureau) are actually what it looks for,
and they are like centroids.
The blocks are pre-indexed for the whole USA, via the data object quadtree aka localtree
}
\seealso{
\code{\link[=ejamit]{ejamit()}} \code{\link[=getblocksnearby_from_fips]{getblocksnearby_from_fips()}} \code{\link[=get_blockpoints_in_shape]{get_blockpoints_in_shape()}}
}
